Technical learning notes, conference insights, and development guides

Author

Dario Airoldi

Published

August 8, 2025

Keywords

learning, development, azure, dotnet, conference, documentation

Quarto Theming and Styling

Overview

Quarto provides extensive theming and styling capabilities that allow you to create visually appealing and professionally designed documentation websites. This guide covers all aspects of Quarto’s theming system, from built-in themes to custom styling approaches.

Overview
Built-in Themes
Theme Configuration
Custom CSS Integration
SCSS Variables and Customization
Bootstrap Integration
Layout Customization
Typography and Fonts
Color Schemes
Responsive Design
Dark Mode Support
Custom Components
Brand Integration
Performance Considerations
Best Practices

Built-in Themes

Quarto comes with a variety of professionally designed themes based on Bootstrap and Bootswatch.

Available Themes

format:
  html:
    theme: default    # Clean, minimal design
    # theme: cerulean  # Blue accent theme
    # theme: cosmo     # Flat, modern design
    # theme: cyborg    # Dark theme with cyan accents
    # theme: darkly    # Dark Bootstrap theme
    # theme: flatly    # Flat UI theme
    # theme: journal   # Newspaper-style theme
    # theme: litera    # Typography-focused theme
    # theme: lumen     # Light theme with warm colors
    # theme: lux       # Elegant theme with serif fonts
    # theme: materia   # Material Design inspired
    # theme: minty     # Fresh, green accent theme
    # theme: morph     # Modern, rounded design
    # theme: pulse     # Purple accent theme
    # theme: quartz    # Professional, clean theme
    # theme: sandstone # Warm, earthy theme
    # theme: simplex   # Minimalist theme
    # theme: sketchy   # Hand-drawn, casual style
    # theme: slate     # Dark theme with cool colors
    # theme: solar     # Solarized color scheme
    # theme: spacelab  # Space-themed design
    # theme: superhero # Dark theme with bright accents
    # theme: united    # Orange accent theme
    # theme: vapor     # Retro, neon-inspired theme
    # theme: yeti      # Clean theme with blue accents
    # theme: zephyr    # Light, airy design

Theme Selection Guidelines

Default: Best for general documentation
Cosmo: Modern, professional look
Flatly: Clean, contemporary design
Darkly/Cyborg: Dark themes for developers
Journal: Academic/research content
Lux: Elegant, serif-based design
Materia: Material Design aesthetic

Theme Configuration

Basic Theme Setup

# _quarto.yml
project:
  type: website

format:
  html:
    theme: cosmo
    css: custom.css
    toc: true
    code-fold: true

Multiple Theme Options

format:
  html:
    theme: 
      - cosmo
      - custom.scss
    css: 
      - styles.css
      - components.css

Theme-Specific Configuration

format:
  html:
    theme: cosmo
    mainfont: "Open Sans"
    monofont: "Fira Code"
    fontsize: 1.1em
    linestretch: 1.7

Custom CSS Integration

Basic CSS Integration

Create a styles.css file:

/* Custom styles for Quarto site */
:root {
  --primary-color: #3498db;
  --secondary-color: #2c3e50;
  --accent-color: #e74c3c;
  --background-color: #ffffff;
  --text-color: #2c3e50;
}

body {
  font-family: 'Inter', sans-serif;
  color: var(--text-color);
  background-color: var(--background-color);
}

.navbar {
  background-color: var(--primary-color) !important;
}

.btn-primary {
  background-color: var(--accent-color);
  border-color: var(--accent-color);
}

Advanced CSS Customization

/* Typography improvements */
h1, h2, h3, h4, h5, h6 {
  font-weight: 600;
  line-height: 1.2;
  margin-top: 2rem;
  margin-bottom: 1rem;
}

/* Code styling */
pre {
  background-color: #f8f9fa;
  border: 1px solid #e9ecef;
  border-radius: 0.375rem;
  padding: 1rem;
}

code {
  background-color: #f1f3f4;
  padding: 0.125rem 0.25rem;
  border-radius: 0.25rem;
  font-size: 0.875em;
}

/* Callout customization */
.callout {
  border-left: 4px solid var(--primary-color);
  padding: 1rem;
  margin: 1.5rem 0;
  background-color: #f8f9fa;
}

.callout-title {
  font-weight: 600;
  color: var(--primary-color);
}

SCSS Variables and Customization

Creating Custom SCSS Theme

Create a custom.scss file:

/*-- scss:defaults --*/
// Import Google Fonts
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap');

// Color palette
$primary: #3498db;
$secondary: #95a5a6;
$success: #27ae60;
$info: #17a2b8;
$warning: #f39c12;
$danger: #e74c3c;
$light: #f8f9fa;
$dark: #2c3e50;

// Typography
$font-family-sans-serif: 'Inter', system-ui, -apple-system, sans-serif;
$font-size-base: 1rem;
$line-height-base: 1.6;

// Layout
$grid-breakpoints: (
  xs: 0,
  sm: 576px,
  md: 768px,
  lg: 992px,
  xl: 1200px,
  xxl: 1400px
);

/*-- scss:rules --*/
// Custom component styles
.hero-section {
  background: linear-gradient(135deg, $primary, darken($primary, 20%));
  color: white;
  padding: 4rem 2rem;
  text-align: center;
  
  h1 {
    font-size: 3rem;
    font-weight: 700;
    margin-bottom: 1rem;
  }
  
  .lead {
    font-size: 1.25rem;
    margin-bottom: 2rem;
  }
}

.feature-card {
  background: white;
  border-radius: 0.5rem;
  padding: 2rem;
  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
  transition: transform 0.3s ease;
  
  &:hover {
    transform: translateY(-5px);
  }
  
  .icon {
    font-size: 3rem;
    color: $primary;
    margin-bottom: 1rem;
  }
}

SCSS Variables Reference

// Brand colors
$primary: #your-brand-color;
$secondary: #your-secondary-color;

// Typography
$headings-font-family: 'Your-Heading-Font', sans-serif;
$font-family-base: 'Your-Body-Font', sans-serif;
$font-size-base: 1rem;
$line-height-base: 1.6;

// Spacing
$spacer: 1rem;
$spacers: (
  0: 0,
  1: $spacer * 0.25,
  2: $spacer * 0.5,
  3: $spacer,
  4: $spacer * 1.5,
  5: $spacer * 3
);

// Borders
$border-radius: 0.375rem;
$border-width: 1px;
$border-color: #dee2e6;

Bootstrap Integration

Bootstrap Classes in Markdown

::: {.container-fluid}

::::{.row}

:::{.col-md-8}
### Main Content
Content goes here
:::

:::{.col-md-4}
### Sidebar
Sidebar content
:::

::::

:::

::: {.alert .alert-info}
**Info:** This is an informational alert using Bootstrap classes.
:::

::: {.btn .btn-primary .btn-lg}
[Large Primary Button](#)
:::

Custom Bootstrap Components

/* Custom button variants */
.btn-outline-custom {
  color: var(--primary-color);
  border-color: var(--primary-color);
}

.btn-outline-custom:hover {
  color: white;
  background-color: var(--primary-color);
  border-color: var(--primary-color);
}

/* Custom card styles */
.card-hover {
  transition: transform 0.3s ease, box-shadow 0.3s ease;
}

.card-hover:hover {
  transform: translateY(-5px);
  box-shadow: 0 8px 25px rgba(0, 0, 0, 0.15);
}

/* Custom navbar styles */
.navbar-custom {
  background: linear-gradient(90deg, var(--primary-color), var(--secondary-color));
}

Layout Customization

Custom Page Layouts

# In document front matter
---
title: "Custom Layout Page"
format:
  html:
    page-layout: custom
    css: page-styles.css
---

Grid System Customization

// Custom grid system
.custom-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 2rem;
  padding: 2rem 0;
}

.grid-item {
  background: white;
  padding: 1.5rem;
  border-radius: 0.5rem;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

// Responsive adjustments
@media (max-width: 768px) {
  .custom-grid {
    grid-template-columns: 1fr;
    gap: 1rem;
    padding: 1rem 0;
  }
}

Header and Footer Customization

<!-- custom-header.html -->
<header class="site-header">
  <div class="container">
    <nav class="navbar navbar-expand-lg">
      <a class="navbar-brand" href="/">
        <img src="logo.svg" alt="Logo" height="40">
      </a>
      <!-- Navigation items -->
    </nav>
  </div>
</header>

Typography and Fonts

Font Configuration

format:
  html:
    theme: cosmo
    mainfont: "Source Sans Pro"
    monofont: "JetBrains Mono"
    fontsize: 1.1em
    linestretch: 1.7

Custom Font Integration

// Import fonts
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@300;400;500&display=swap');

// Font variables
$font-family-base: 'Inter', system-ui, sans-serif;
$font-family-monospace: 'JetBrains Mono', 'SF Mono', Consolas, monospace;

// Typography scale
$font-sizes: (
  xs: 0.75rem,
  sm: 0.875rem,
  base: 1rem,
  lg: 1.125rem,
  xl: 1.25rem,
  2xl: 1.5rem,
  3xl: 1.875rem,
  4xl: 2.25rem,
  5xl: 3rem
);

// Apply typography
body {
  font-family: $font-family-base;
  font-size: map-get($font-sizes, base);
  line-height: 1.6;
}

h1 { font-size: map-get($font-sizes, 4xl); }
h2 { font-size: map-get($font-sizes, 3xl); }
h3 { font-size: map-get($font-sizes, 2xl); }

Color Schemes

Defining Color Palettes

// Primary palette
$colors: (
  "primary": #3498db,
  "secondary": #95a5a6,
  "accent": #e74c3c,
  "success": #27ae60,
  "warning": #f39c12,
  "danger": #e74c3c,
  "info": #17a2b8,
  "light": #f8f9fa,
  "dark": #2c3e50
);

// Generate utility classes
@each $name, $color in $colors {
  .text-#{$name} {
    color: $color !important;
  }
  
  .bg-#{$name} {
    background-color: $color !important;
  }
  
  .border-#{$name} {
    border-color: $color !important;
  }
}

Semantic Color Usage

/* Semantic color system */
:root {
  /* Brand colors */
  --brand-primary: #3498db;
  --brand-secondary: #2c3e50;
  
  /* Semantic colors */
  --color-success: #27ae60;
  --color-warning: #f39c12;
  --color-error: #e74c3c;
  --color-info: #17a2b8;
  
  /* Neutral colors */
  --color-text: #2c3e50;
  --color-text-muted: #6c757d;
  --color-background: #ffffff;
  --color-surface: #f8f9fa;
  --color-border: #dee2e6;
}

Responsive Design

Responsive Typography

// Responsive font sizes
@mixin responsive-font-size($min-size, $max-size) {
  font-size: clamp(#{$min-size}, 4vw, #{$max-size});
}

h1 {
  @include responsive-font-size(2rem, 4rem);
  font-weight: 700;
  line-height: 1.1;
}

h2 {
  @include responsive-font-size(1.5rem, 3rem);
  font-weight: 600;
  line-height: 1.2;
}

// Responsive spacing
@media (max-width: 768px) {
  .container {
    padding-left: 1rem;
    padding-right: 1rem;
  }
  
  .section {
    padding-top: 2rem;
    padding-bottom: 2rem;
  }
}

Mobile-First Approach

// Mobile-first responsive design
.feature-grid {
  display: grid;
  grid-template-columns: 1fr;
  gap: 1rem;
  
  @media (min-width: 576px) {
    grid-template-columns: repeat(2, 1fr);
    gap: 1.5rem;
  }
  
  @media (min-width: 992px) {
    grid-template-columns: repeat(3, 1fr);
    gap: 2rem;
  }
}

Dark Mode Support

Dark Mode Configuration

format:
  html:
    theme: 
      light: cosmo
      dark: darkly

Custom Dark Mode Styles

// Dark mode variables
[data-bs-theme="dark"] {
  --color-background: #1a1a1a;
  --color-surface: #2d2d2d;
  --color-text: #ffffff;
  --color-text-muted: #a0a0a0;
  --color-border: #404040;
}

// Dark mode specific styles
@media (prefers-color-scheme: dark) {
  .custom-component {
    background-color: var(--color-surface);
    color: var(--color-text);
    border-color: var(--color-border);
  }
}

Custom Components

Creating Reusable Components

// Hero section component
.hero {
  background: linear-gradient(135deg, var(--brand-primary), darken(var(--brand-primary), 20%));
  color: white;
  padding: 4rem 2rem;
  text-align: center;
  
  &__title {
    font-size: 3.5rem;
    font-weight: 700;
    margin-bottom: 1rem;
    
    @media (max-width: 768px) {
      font-size: 2.5rem;
    }
  }
  
  &__subtitle {
    font-size: 1.25rem;
    opacity: 0.9;
    margin-bottom: 2rem;
  }
  
  &__cta {
    display: inline-flex;
    gap: 1rem;
    margin-top: 1rem;
  }
}

// Card component
.feature-card {
  background: white;
  border-radius: 0.75rem;
  padding: 2rem;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.05);
  transition: all 0.3s ease;
  
  &:hover {
    transform: translateY(-4px);
    box-shadow: 0 12px 25px rgba(0, 0, 0, 0.1);
  }
  
  &__icon {
    width: 4rem;
    height: 4rem;
    background: var(--brand-primary);
    border-radius: 50%;
    display: flex;
    align-items: center;
    justify-content: center;
    margin-bottom: 1.5rem;
    
    svg {
      width: 2rem;
      height: 2rem;
      fill: white;
    }
  }
  
  &__title {
    font-size: 1.25rem;
    font-weight: 600;
    margin-bottom: 0.75rem;
  }
  
  &__description {
    color: var(--color-text-muted);
    line-height: 1.6;
  }
}

Brand Integration

Brand Configuration

// Brand system
$brand-colors: (
  primary: #your-primary-color,
  secondary: #your-secondary-color,
  accent: #your-accent-color
);

$brand-fonts: (
  heading: 'Your-Brand-Font',
  body: 'Your-Body-Font',
  mono: 'Your-Mono-Font'
);

// Logo integration
.site-logo {
  height: 2.5rem;
  width: auto;
  
  @media (max-width: 768px) {
    height: 2rem;
  }
}

// Brand-consistent spacing
$brand-spacing: (
  xs: 0.25rem,
  sm: 0.5rem,
  md: 1rem,
  lg: 1.5rem,
  xl: 2rem,
  xxl: 3rem
);

Style Guide Implementation

// Style guide components
.style-guide {
  &__color-swatch {
    width: 100px;
    height: 100px;
    border-radius: 0.5rem;
    display: flex;
    align-items: center;
    justify-content: center;
    color: white;
    font-weight: 600;
    text-shadow: 0 1px 2px rgba(0, 0, 0, 0.3);
  }
  
  &__typography-sample {
    margin-bottom: 2rem;
    
    h1, h2, h3, h4, h5, h6 {
      margin-bottom: 0.5rem;
    }
  }
}

Performance Considerations

CSS Optimization

// Efficient CSS practices
.component {
  // Use efficient selectors
  &__element {
    // Avoid deep nesting
  }
  
  // Use CSS custom properties for theming
  background-color: var(--component-bg, #ffffff);
  color: var(--component-text, #333333);
}

// Minimize unused CSS
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/mixins";

// Only import needed components
@import "bootstrap/scss/root";
@import "bootstrap/scss/reboot";
@import "bootstrap/scss/type";
@import "bootstrap/scss/grid";
@import "bootstrap/scss/utilities";

Loading Optimization

format:
  html:
    theme: cosmo
    css: 
      - href: styles.css
        preload: true
    include-in-header: |
      <link rel="preconnect" href="https://fonts.googleapis.com">
      <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>

Best Practices

1. Design System Approach

Consistency: Use a consistent color palette and typography
Modularity: Create reusable component styles
Documentation: Document your design decisions
Accessibility: Ensure sufficient color contrast and readability

2. Performance

Minimize CSS: Only include necessary styles
Optimize Images: Use appropriate formats and sizes
Font Loading: Use font-display: swap for better performance
Critical CSS: Inline critical styles for faster rendering

3. Maintainability

Variables: Use CSS custom properties or SCSS variables
Organization: Structure CSS with clear naming conventions
Comments: Document complex styles and calculations
Version Control: Track changes to design system

4. Responsive Design

Mobile First: Design for mobile devices first
Progressive Enhancement: Add features for larger screens
Touch Targets: Ensure interactive elements are appropriately sized
Content Priority: Prioritize important content on smaller screens

5. Accessibility

Color Contrast: Maintain WCAG AA standards (4.5:1 ratio)
Focus States: Provide clear focus indicators
Screen Readers: Use semantic HTML and ARIA labels
Motion: Respect prefers-reduced-motion settings

Resources

This comprehensive guide covers all aspects of Quarto theming and styling, from basic theme selection to advanced custom component creation. Use these techniques to create professional, branded documentation that reflects your organization’s visual identity.

# Quarto Theming and Styling ## Overview Quarto provides extensive theming and styling capabilities that allow you to create visually appealing and professionally designed documentation websites. This guide covers all aspects of Quarto's theming system, from built-in themes to custom styling approaches. ## Table of Contents - [Overview](#overview) - [Built-in Themes](#built-in-themes) - [Theme Configuration](#theme-configuration) - [Custom CSS Integration](#custom-css-integration) - [SCSS Variables and Customization](#scss-variables-and-customization) - [Bootstrap Integration](#bootstrap-integration) - [Layout Customization](#layout-customization) - [Typography and Fonts](#typography-and-fonts) - [Color Schemes](#color-schemes) - [Responsive Design](#responsive-design) - [Dark Mode Support](#dark-mode-support) - [Custom Components](#custom-components) - [Brand Integration](#brand-integration) - [Performance Considerations](#performance-considerations) - [Best Practices](#best-practices) ## Built-in Themes Quarto comes with a variety of professionally designed themes based on Bootstrap and Bootswatch. ### Available Themes ```yaml format: html: theme: default # Clean, minimal design # theme: cerulean # Blue accent theme # theme: cosmo # Flat, modern design # theme: cyborg # Dark theme with cyan accents # theme: darkly # Dark Bootstrap theme # theme: flatly # Flat UI theme # theme: journal # Newspaper-style theme # theme: litera # Typography-focused theme # theme: lumen # Light theme with warm colors # theme: lux # Elegant theme with serif fonts # theme: materia # Material Design inspired # theme: minty # Fresh, green accent theme # theme: morph # Modern, rounded design # theme: pulse # Purple accent theme # theme: quartz # Professional, clean theme # theme: sandstone # Warm, earthy theme # theme: simplex # Minimalist theme # theme: sketchy # Hand-drawn, casual style # theme: slate # Dark theme with cool colors # theme: solar # Solarized color scheme # theme: spacelab # Space-themed design # theme: superhero # Dark theme with bright accents # theme: united # Orange accent theme # theme: vapor # Retro, neon-inspired theme # theme: yeti # Clean theme with blue accents # theme: zephyr # Light, airy design ``` ### Theme Selection Guidelines - **Default**: Best for general documentation - **Cosmo**: Modern, professional look - **Flatly**: Clean, contemporary design - **Darkly/Cyborg**: Dark themes for developers - **Journal**: Academic/research content - **Lux**: Elegant, serif-based design - **Materia**: Material Design aesthetic ## Theme Configuration ### Basic Theme Setup ```yaml # _quarto.yml project: type: website format: html: theme: cosmo css: custom.css toc: true code-fold: true ``` ### Multiple Theme Options ```yaml format: html: theme: - cosmo - custom.scss css: - styles.css - components.css ``` ### Theme-Specific Configuration ```yaml format: html: theme: cosmo mainfont: "Open Sans" monofont: "Fira Code" fontsize: 1.1em linestretch: 1.7 ``` ## Custom CSS Integration ### Basic CSS Integration Create a `styles.css` file: ```css /* Custom styles for Quarto site */ :root { --primary-color: #3498db; --secondary-color: #2c3e50; --accent-color: #e74c3c; --background-color: #ffffff; --text-color: #2c3e50; } body { font-family: 'Inter', sans-serif; color: var(--text-color); background-color: var(--background-color); } .navbar { background-color: var(--primary-color) !important; } .btn-primary { background-color: var(--accent-color); border-color: var(--accent-color); } ``` ### Advanced CSS Customization ```css /* Typography improvements */ h1, h2, h3, h4, h5, h6 { font-weight: 600; line-height: 1.2; margin-top: 2rem; margin-bottom: 1rem; } /* Code styling */ pre { background-color: #f8f9fa; border: 1px solid #e9ecef; border-radius: 0.375rem; padding: 1rem; } code { background-color: #f1f3f4; padding: 0.125rem 0.25rem; border-radius: 0.25rem; font-size: 0.875em; } /* Callout customization */ .callout { border-left: 4px solid var(--primary-color); padding: 1rem; margin: 1.5rem 0; background-color: #f8f9fa; } .callout-title { font-weight: 600; color: var(--primary-color); } ``` ## SCSS Variables and Customization ### Creating Custom SCSS Theme Create a `custom.scss` file: ```scss /*-- scss:defaults --*/ // Import Google Fonts @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap'); // Color palette $primary: #3498db; $secondary: #95a5a6; $success: #27ae60; $info: #17a2b8; $warning: #f39c12; $danger: #e74c3c; $light: #f8f9fa; $dark: #2c3e50; // Typography $font-family-sans-serif: 'Inter', system-ui, -apple-system, sans-serif; $font-size-base: 1rem; $line-height-base: 1.6; // Layout $grid-breakpoints: ( xs: 0, sm: 576px, md: 768px, lg: 992px, xl: 1200px, xxl: 1400px ); /*-- scss:rules --*/ // Custom component styles .hero-section { background: linear-gradient(135deg, $primary, darken($primary, 20%)); color: white; padding: 4rem 2rem; text-align: center; h1 { font-size: 3rem; font-weight: 700; margin-bottom: 1rem; } .lead { font-size: 1.25rem; margin-bottom: 2rem; } } .feature-card { background: white; border-radius: 0.5rem; padding: 2rem; box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1); transition: transform 0.3s ease; &:hover { transform: translateY(-5px); } .icon { font-size: 3rem; color: $primary; margin-bottom: 1rem; } } ``` ### SCSS Variables Reference ```scss // Brand colors $primary: #your-brand-color; $secondary: #your-secondary-color; // Typography $headings-font-family: 'Your-Heading-Font', sans-serif; $font-family-base: 'Your-Body-Font', sans-serif; $font-size-base: 1rem; $line-height-base: 1.6; // Spacing $spacer: 1rem; $spacers: ( 0: 0, 1: $spacer * 0.25, 2: $spacer * 0.5, 3: $spacer, 4: $spacer * 1.5, 5: $spacer * 3 ); // Borders $border-radius: 0.375rem; $border-width: 1px; $border-color: #dee2e6; ``` ## Bootstrap Integration ### Bootstrap Classes in Markdown ```markdown ::: {.container-fluid} ::::{.row} :::{.col-md-8} ### Main Content Content goes here ::: :::{.col-md-4} ### Sidebar Sidebar content ::: :::: ::: ::: {.alert .alert-info} **Info:** This is an informational alert using Bootstrap classes. ::: ::: {.btn .btn-primary .btn-lg} [Large Primary Button](#) ::: ``` ### Custom Bootstrap Components ```css /* Custom button variants */ .btn-outline-custom { color: var(--primary-color); border-color: var(--primary-color); } .btn-outline-custom:hover { color: white; background-color: var(--primary-color); border-color: var(--primary-color); } /* Custom card styles */ .card-hover { transition: transform 0.3s ease, box-shadow 0.3s ease; } .card-hover:hover { transform: translateY(-5px); box-shadow: 0 8px 25px rgba(0, 0, 0, 0.15); } /* Custom navbar styles */ .navbar-custom { background: linear-gradient(90deg, var(--primary-color), var(--secondary-color)); } ``` ## Layout Customization ### Custom Page Layouts ```yaml # In document front matter --- title: "Custom Layout Page" format: html: page-layout: custom css: page-styles.css --- ``` ### Grid System Customization ```scss // Custom grid system .custom-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 2rem; padding: 2rem 0; } .grid-item { background: white; padding: 1.5rem; border-radius: 0.5rem; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1); } // Responsive adjustments @media (max-width: 768px) { .custom-grid { grid-template-columns: 1fr; gap: 1rem; padding: 1rem 0; } } ``` ### Header and Footer Customization ```html  <header class="site-header"> <div class="container"> <nav class="navbar navbar-expand-lg"> <a class="navbar-brand" href="/"> <img src="logo.svg" alt="Logo" height="40"> </a>  </nav> </div> </header> ``` ## Typography and Fonts ### Font Configuration ```yaml format: html: theme: cosmo mainfont: "Source Sans Pro" monofont: "JetBrains Mono" fontsize: 1.1em linestretch: 1.7 ``` ### Custom Font Integration ```scss // Import fonts @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@300;400;500&display=swap'); // Font variables $font-family-base: 'Inter', system-ui, sans-serif; $font-family-monospace: 'JetBrains Mono', 'SF Mono', Consolas, monospace; // Typography scale $font-sizes: ( xs: 0.75rem, sm: 0.875rem, base: 1rem, lg: 1.125rem, xl: 1.25rem, 2xl: 1.5rem, 3xl: 1.875rem, 4xl: 2.25rem, 5xl: 3rem ); // Apply typography body { font-family: $font-family-base; font-size: map-get($font-sizes, base); line-height: 1.6; } h1 { font-size: map-get($font-sizes, 4xl); } h2 { font-size: map-get($font-sizes, 3xl); } h3 { font-size: map-get($font-sizes, 2xl); } ``` ## Color Schemes ### Defining Color Palettes ```scss // Primary palette $colors: ( "primary": #3498db, "secondary": #95a5a6, "accent": #e74c3c, "success": #27ae60, "warning": #f39c12, "danger": #e74c3c, "info": #17a2b8, "light": #f8f9fa, "dark": #2c3e50 ); // Generate utility classes @each $name, $color in $colors { .text-#{$name} { color: $color !important; } .bg-#{$name} { background-color: $color !important; } .border-#{$name} { border-color: $color !important; } } ``` ### Semantic Color Usage ```css /* Semantic color system */ :root { /* Brand colors */ --brand-primary: #3498db; --brand-secondary: #2c3e50; /* Semantic colors */ --color-success: #27ae60; --color-warning: #f39c12; --color-error: #e74c3c; --color-info: #17a2b8; /* Neutral colors */ --color-text: #2c3e50; --color-text-muted: #6c757d; --color-background: #ffffff; --color-surface: #f8f9fa; --color-border: #dee2e6; } ``` ## Responsive Design ### Responsive Typography ```scss // Responsive font sizes @mixin responsive-font-size($min-size, $max-size) { font-size: clamp(#{$min-size}, 4vw, #{$max-size}); } h1 { @include responsive-font-size(2rem, 4rem); font-weight: 700; line-height: 1.1; } h2 { @include responsive-font-size(1.5rem, 3rem); font-weight: 600; line-height: 1.2; } // Responsive spacing @media (max-width: 768px) { .container { padding-left: 1rem; padding-right: 1rem; } .section { padding-top: 2rem; padding-bottom: 2rem; } } ``` ### Mobile-First Approach ```scss // Mobile-first responsive design .feature-grid { display: grid; grid-template-columns: 1fr; gap: 1rem; @media (min-width: 576px) { grid-template-columns: repeat(2, 1fr); gap: 1.5rem; } @media (min-width: 992px) { grid-template-columns: repeat(3, 1fr); gap: 2rem; } } ``` ## Dark Mode Support ### Dark Mode Configuration ```yaml format: html: theme: light: cosmo dark: darkly ``` ### Custom Dark Mode Styles ```scss // Dark mode variables [data-bs-theme="dark"] { --color-background: #1a1a1a; --color-surface: #2d2d2d; --color-text: #ffffff; --color-text-muted: #a0a0a0; --color-border: #404040; } // Dark mode specific styles @media (prefers-color-scheme: dark) { .custom-component { background-color: var(--color-surface); color: var(--color-text); border-color: var(--color-border); } } ``` ## Custom Components ### Creating Reusable Components ```scss // Hero section component .hero { background: linear-gradient(135deg, var(--brand-primary), darken(var(--brand-primary), 20%)); color: white; padding: 4rem 2rem; text-align: center; &__title { font-size: 3.5rem; font-weight: 700; margin-bottom: 1rem; @media (max-width: 768px) { font-size: 2.5rem; } } &__subtitle { font-size: 1.25rem; opacity: 0.9; margin-bottom: 2rem; } &__cta { display: inline-flex; gap: 1rem; margin-top: 1rem; } } // Card component .feature-card { background: white; border-radius: 0.75rem; padding: 2rem; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.05); transition: all 0.3s ease; &:hover { transform: translateY(-4px); box-shadow: 0 12px 25px rgba(0, 0, 0, 0.1); } &__icon { width: 4rem; height: 4rem; background: var(--brand-primary); border-radius: 50%; display: flex; align-items: center; justify-content: center; margin-bottom: 1.5rem; svg { width: 2rem; height: 2rem; fill: white; } } &__title { font-size: 1.25rem; font-weight: 600; margin-bottom: 0.75rem; } &__description { color: var(--color-text-muted); line-height: 1.6; } } ``` ## Brand Integration ### Brand Configuration ```scss // Brand system $brand-colors: ( primary: #your-primary-color, secondary: #your-secondary-color, accent: #your-accent-color ); $brand-fonts: ( heading: 'Your-Brand-Font', body: 'Your-Body-Font', mono: 'Your-Mono-Font' ); // Logo integration .site-logo { height: 2.5rem; width: auto; @media (max-width: 768px) { height: 2rem; } } // Brand-consistent spacing $brand-spacing: ( xs: 0.25rem, sm: 0.5rem, md: 1rem, lg: 1.5rem, xl: 2rem, xxl: 3rem ); ``` ### Style Guide Implementation ```scss // Style guide components .style-guide { &__color-swatch { width: 100px; height: 100px; border-radius: 0.5rem; display: flex; align-items: center; justify-content: center; color: white; font-weight: 600; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.3); } &__typography-sample { margin-bottom: 2rem; h1, h2, h3, h4, h5, h6 { margin-bottom: 0.5rem; } } } ``` ## Performance Considerations ### CSS Optimization ```scss // Efficient CSS practices .component { // Use efficient selectors &__element { // Avoid deep nesting } // Use CSS custom properties for theming background-color: var(--component-bg, #ffffff); color: var(--component-text, #333333); } // Minimize unused CSS @import "bootstrap/scss/functions"; @import "bootstrap/scss/variables"; @import "bootstrap/scss/mixins"; // Only import needed components @import "bootstrap/scss/root"; @import "bootstrap/scss/reboot"; @import "bootstrap/scss/type"; @import "bootstrap/scss/grid"; @import "bootstrap/scss/utilities"; ``` ### Loading Optimization ```yaml format: html: theme: cosmo css: - href: styles.css preload: true include-in-header: | <link rel="preconnect" href="https://fonts.googleapis.com"> <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> ``` ## Best Practices ### 1. Design System Approach - **Consistency**: Use a consistent color palette and typography - **Modularity**: Create reusable component styles - **Documentation**: Document your design decisions - **Accessibility**: Ensure sufficient color contrast and readability ### 2. Performance - **Minimize CSS**: Only include necessary styles - **Optimize Images**: Use appropriate formats and sizes - **Font Loading**: Use font-display: swap for better performance - **Critical CSS**: Inline critical styles for faster rendering ### 3. Maintainability - **Variables**: Use CSS custom properties or SCSS variables - **Organization**: Structure CSS with clear naming conventions - **Comments**: Document complex styles and calculations - **Version Control**: Track changes to design system ### 4. Responsive Design - **Mobile First**: Design for mobile devices first - **Progressive Enhancement**: Add features for larger screens - **Touch Targets**: Ensure interactive elements are appropriately sized - **Content Priority**: Prioritize important content on smaller screens ### 5. Accessibility - **Color Contrast**: Maintain WCAG AA standards (4.5:1 ratio) - **Focus States**: Provide clear focus indicators - **Screen Readers**: Use semantic HTML and ARIA labels - **Motion**: Respect prefers-reduced-motion settings ## Resources - [Bootstrap Documentation](https://getbootstrap.com/) - [Sass Documentation](https://sass-lang.com/) - [MDN CSS Reference](https://developer.mozilla.org/en-US/docs/Web/CSS) - [Web Content Accessibility Guidelines](https://www.w3.org/WAI/WCAG21/quickref/) - [Google Fonts](https://fonts.google.com/) --- This comprehensive guide covers all aspects of Quarto theming and styling, from basic theme selection to advanced custom component creation. Use these techniques to create professional, branded documentation that reflects your organization's visual identity.